/*********************************************************************
*
* Software License Agreement (BSD License)
*
*  Copyright (c) 2008, Willow Garage, Inc.
*  All rights reserved.
*
*  Redistribution and use in source and binary forms, with or without
*  modification, are permitted provided that the following conditions
*  are met:
*
*   * Redistributions of source code must retain the above copyright
*     notice, this list of conditions and the following disclaimer.
*   * Redistributions in binary form must reproduce the above
*     copyright notice, this list of conditions and the following
*     disclaimer in the documentation and/or other materials provided
*     with the distribution.
*   * Neither the name of the Willow Garage nor the names of its
*     contributors may be used to endorse or promote products derived
*     from this software without specific prior written permission.
*
*  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
*  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
*  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
*  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
*  COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
*  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
*  BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
*  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
*  CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
*  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
*  ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
*  POSSIBILITY OF SUCH DAMAGE.
*
* Author: Eitan Marder-Eppstein
*********************************************************************/
#ifndef TRAJECTORY_ROLLOUT_COSTMAP_MODEL_
#define TRAJECTORY_ROLLOUT_COSTMAP_MODEL_

#include <base_local_planner/world_model.h>
// For obstacle data access
#include <costmap_2d/costmap_2d.h>

namespace base_local_planner
{
/**
 * @class CostmapModel
 * @brief A class that implements the WorldModel interface to provide grid
 * based collision checks for the trajectory controller using the costmap.
 * 这个类帮助局部规划器在Costmap上进行计算，
 * footprintCost、lineCost、pointCost三个类方法分别能通过Costmap计算出机器人足迹范围、两个cell连线、单个cell的代价，并将值返回给局部规划器。
 */
class CostmapModel : public WorldModel
{
public:
    /**
     * @brief  Constructor for the CostmapModel 构造代价地图模型
     * @param costmap The costmap that should be used 用到的代价函数
     * @return
     */
    CostmapModel(const costmap_2d::Costmap2D &costmap);

    /**
     * @brief  Destructor for the world model 世界模型的析构函数
     */
    virtual ~CostmapModel() {}

    using WorldModel::footprintCost;

    /** 检查是否有障碍物落到凸footprint里面，其中footprint已经被栅格化成网格
     * @brief  Checks if any obstacles in the costmap lie inside a convex footprint that is rasterized into the grid
     * @param  position The position of the robot in world coordinates                        机器人位置
     * @param  footprint The specification of the footprint of the robot in world coordinates 机器人的footprint
     * @param  inscribed_radius The radius of the inscribed circle of the robot               机器人的内切圆半径
     * @param  circumscribed_radius The radius of the circumscribed circle of the robot       机器人的外接圆半径
     * @return Positive if all the points lie outside the footprint, negative otherwise:
     *            -1 if footprint covers at least a lethal obstacle cell, or
     *            -2 if footprint covers at least a no-information cell, or
     *            -3 if footprint is [partially] outside of the map
     * @return 返回正数如果所有的点都在footprint外部，负数则分别代表:
     *            -1 代表 footprint 碰到至少一个致命的障碍物单元格(lethal obstacle cell)
     *            -2 代表 footprint 碰到至少一个无信息单元格 (no-information cell)
     *            -3 代表 footprint 有一部分在地图外面
     * 若预设的足迹点数 < 3，考虑足迹的形状没有意义，这时只计算机器人位置点在costmap上的代价；
     * 若预设的足迹点数 ≥ 3，把足迹视为多边形，循环调用lineCost计算多边形各边的cell，注意首尾闭合，最后返回代价。
     */
    virtual double footprintCost(const geometry_msgs::Point &position, const std::vector<geometry_msgs::Point> &footprint,
                  double inscribed_radius, double circumscribed_radius);

    /** 栅格化一条线段到代价地图网格并且进行碰撞检测
     * @brief  Rasterizes a line in the costmap grid and checks for collisions
     * @param x0 The x position of the first cell in grid coordinates 网格坐标系中第一个单元格的x坐标
     * @param y0 The y position of the first cell in grid coordinates 网格坐标系中第一个单元格的y坐标
     * @param x1 The x position of the second cell in grid coordinates 网格坐标系中第二个单元格的x坐标
     * @param y1 The y position of the second cell in grid coordinates 网格坐标系中第二个单元格的y坐标
     * @return A positive cost for a legal line... negative otherwise 对于合法的线段返回正值的代价
     */
    double lineCost(int x0, int x1, int y0, int y1) const;

    /**
     * @brief  Checks the cost of a point in the costmap 检查某个点在代价地图中的代价
     * @param x The x position of the point in cell coordinates 点在单元格坐标系中的x坐标
     * @param y The y position of the point in cell coordinates 点在单元格坐标系中的y坐标
     * @return A positive cost for a legal point... negative otherwise 对于合法的线段返回正值的代价
     */
    double pointCost(int x, int y) const;

private:
    const costmap_2d::Costmap2D &costmap_; // Allows access of costmap obstacle information

};
};
#endif
